Copyright: Copyright (c) 1996 Michel Brazeau


Spider Containers for Object Pascal

Spider containers is a set of container classes for Borland's Object Pascal language. It is compatible with the Object Pascal implementation found in versions 1.0 and 2.0 of Borland's Delphi product. This class library was motivated by the lack of generic classes (called templates in C++) in the language definition. All the container classes are type-safe; that is, when a container is created, the type of object that the container may hold is specified, and all additions to the container must be of that type. For example, if a list is created to hold TButton instances, then only instances of TButton (or derived classes) may be inserted in the container; otherwise a run-time exception is raised.

Overview and general principles

Which container should I use?

Classes

Units

Exceptions

Multi-Language Support

Evaluation Version

How To Purchase

Licensing and Legal Information

Contact Information


Overview and general principles

Spider container classes use run-time type information (RTTI) provided by the Object Pascal language to implement type safe containers.

Object Pascal offers an elegant object model where all classes inherit from TObject.  This common ancestor ensures that all objects stored inside containers may be destroyed uniformly. Furthermore,  the reference model where each object instance refers to a dynamic instance on the heap,  allows the container classes to use TObject as the basic storage unit without concern of an instance data size.

For more information, select any of the following topics:

Type Safety

Automatic Destruction of Objects

Comparing Objects

Storing Non-Object Data in Containers

Iterating Through the Contents of a Container

Compilation Constants


Type Safety

At creation time, the type of object to be held by a container is specified. Only objects of the specified type (or derived types) may be added to the container.  If an object of an improper type is added to a container, the EInvalidObjectType exception is raised. For example, if a stack is created with the following invocation,

Stack := TStack.Create(TMyObject)

and an attempt to Push an object of type TYourObject (which is not a descendent of TMyObject) with the following invocation,

Stack.Push(YourObject)

will raise the EInvalidObjectType exception.

When removing or accessing objects, type casting is necessary because container classes treat all objects uniformly as TObject's.  The type checking has already been perform when objects are added to containers, so type safety is not compromised.  The type cast may be performed with the as operator,  or using the direct style:

MyObject := TStack.Pop as TMyObject;

or

MyObject := TMyObject(TStack.Pop);


Automatic Destruction of Objects

All objects held by a container will be destroyed when the container itself is destroyed.  For example, in the following lines, objects A and B do not need to be destroyed explicitly; they will be destroyed by the Queue.

  Queue := TQueue.Create(TMyObject);

  A     := TMyObject.Create;

  B     := TMyObject.Create;

  Queue.Enqueue(A);

  Queue.Enqueue(B);

  { the container and all held objects are destroyed }

  Queue.Destroy;


Comparing Objects

Containers which keep their objects in a specific order and/or allow searching,  need the ability to compare objects.  A comparison function must be supplied at creation time for such containers.  The TComparisonFunc type defines the form of the function.

Here is an example of the usage of a comparison function.

Given this very simple class,

TMyObject = class

    Name : String;

end;

you may use this comparison function:

function CompareMyObject( const Lhs, Rhs : TObject) : TComparison;

begin

    if (Lhs as TMyObject).Name <

       (Rhs as TMyObject).Name then

        Result := cmpLess

    else if (Lhs as TMyObject).Name >

            (Rhs as TMyObject).Name then

        Result := cmpGreater

    else

        Result := cmpEqual;

end;

Now you may create a container that requires a comparison function to hold TMyObject instances as follows:

List := TOrderedList.Create(TMyObject, CompareMyObject);


Storing Non-Object Data in Containers

All containers can store any object derived from TObject.  In an ideal object oriented world this is fine.  But in hybrid languages like Object Pascal, which support both object oriented and procedural paradigms, not everything is an object.  For example standard types such as Char's, LongInt's, Double's, and pascal records are not object oriented classes.

Special bucket classes are available to store non-object data in containers. Bucket classes are provided for common pascal types, and the TBucket class may be used to store any non-object data.

Here is an example to store a pascal record type inside a TQueue container.

TPerson = record

    LastName  : String[40];

    FirstName : String[40];

end;

{ create a queue to hold TBucket's }

Queue := TQueue.Create(TBucket);

Person.LastName  := 'Doe';

Person.FirstName := 'John';

{ create a bucket to hold the record }

Bucket := TBucket.CreateSetData(SizeOf(Person), Person));

{ add the bucket to the container }

Queue.EnQueue(Bucket);

{ retrieve the bucket from the container }

Bucket := Queue.DeQueue as TBucket;

{ retrieve the record from the bucket }

Bucket.GetData(Person);

{ since the bucket has been removed from the container it must be destroyed explicitly }

Bucket.Destroy;

{ destroy the queue }

Queue.Destroy;


Iterating Through the Contents of a Container

It is often necessary to iterate through the contents of a container to perform various processing on the held objects.  The base class TContainer provides iterator methods which may be used on all derived containers.

The iterator methods require a procedure or method type as parameter.  This routine will be invoked for each object in the container.  The ForEachCallProc method requires a file level procedure, while the ForEachCallMethod requires the method of an object as parameter.

Here is an example of how to use an iterator method.

Given a list that contains objects of the following type,

TInvoiceItem = class

    Quantity    : Word;

    Description : String;

    UnitPrice   : Double;

    Total       : Double;

end;

the following iterator method will be used to compute the total cost of all invoice items in the list,

procedure TMyForm.InvoiceIterator(const Obj : TObject);

begin

    with Obj as TInvoiceItem do

        TotalCost := TotalCost + Total;

end;

TotalCost should be a private data member of TMyForm class.  Assuming that List is a properly constructed container holding TInvoiceItem's, the following lines will calculate the total cost of all the invoice items in the list.

TotalCost := 0;

List.ForEachCallMethod(InvoiceIterator);


Compilation Constants for Spider Containers

The source include file, Contain.Inc, defines compilation directives that are mandatory for the Spider containers.

The compilation constant, __RemoveTypeSafety, may be defined by changing the line,

{.$define __RemoveTypeSafety}

to

{$define __RemoveTypeSafety}

Once an application has been debugged,  it may be desired to remove the run-time type identification overhead.  Note that in most applications, this overhead will not be noticeable, so it is recommended to not define this constant, because there may still be unfound bugs even in a production version of an application.


Spider Library Classes

TContainer

TArray

THashTable

TNodeContainer

TBinaryTree

TOrderedList

TUnOrderedList

TCircularList

TQueue

TPriorityQueue

TStack

TStringTable

TStringCombo

TBucket

TBooleanBucket

TByteBucket

TCharBucket

TCompBucket

TDateTimeBucket

TDoubleBucket

TExtendedBucket

TIntegerBucket

TLongBoolBucket

TLongIntBucket

TRealBucket

TShortIntBucket

TSingleBucket

TWordBoolBucket

TWordBucket


TContainer Class

Properties	Methods

Unit

ObjBase

Description

TContainer is the base class of all containers. All containers have a read-only Size property, which returns the number of objects currently stored in the container, and provides the IsEmpty property to query if the container is empty.

The Create constructor of TContainer is passed a TClass variable which identifies which type of objects may be inserted in the container. The Destroy destructor, destroys the container and also destroys all objects inside the container.

The Clear method empties the container, and destroys every contained object.

TContainer also declares the iterator methods, ForEachCallProc and ForEachCallMethod, which call a user defined procedure or method respectively, for each object in the container.

All exceptions generated for container classes are centralized in class methods belonging to TContainer, which may be called without a TContainer instance. This facilitates the maintenance of exception messages.


Create Method

Applies to

All container classes

Create method for TArray

Create method for TOrderedList

Create method for TUnOrderedList

Create method for TCircularList

Create method for TBinaryTree

Create method for THashTable

Create method for TStringTable

Create method for TQueue

Create method for TPriorityQueue

Create method for TStack


TContainer Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Class Methods

RaiseInvalidObjectType

RaiseContainerIsEmpty

RaiseInvalidIndex

RaiseMarkerNotSet

RaiseNewArraySizeTooSmall

RaiseContainerIsFull

RaiseArrayNotSorted

RaiseInvalidOccurrenceSought

RaiseInvalidArrayCapacity


Create Method

Applies to

TContainer

Declaration

constructor Create(const InObjectType : TClass);

Description

Creates a container that may only hold instances of objects belonging to InObjectType or derived classes.


Destroy Method

Applies to

TContainer

Declaration

destructor Destroy; override;

Description

Destroys the container, and all the objects contained are also destroyed.


Clear Method

Applies to

TContainer

Declaration

procedure Clear; virtual; abstract;

Description

Clears and destroys all the objects in the container. After invoking Clear, the Size property will return 0, and the IsEmpty property will return True.


ForEachCallProc Method

See Also

Applies to

TContainer

Declaration

procedure ForEachCallProc(const ProcIterator : TProcIterator); virtual; abstract;

Description

The procedure ProcIterator is invoked for each object in the container.


ForEachCallProc Method See Also
See Also

ForEachCallMethod method


ForEachCallMethod Method

See Also

Applies to

TContainer

Declaration

procedure ForEachCallMethod(const MethodIterator : TMethodIterator); virtual; abstract;

Description

The method MethodIterator is invoked for each object in the container.


ForEachCallMethod Method See Also
See Also

ForEachCallProc method


RaiseInvalidObjectType Method

Applies to

TContainer

Declaration

class procedure RaiseInvalidObjectType;

Description

Raises the EInvalidObjectType exception.


RaiseContainerIsEmpty Method

Applies to

TContainer

Declaration

class procedure RaiseContainerIsEmpty;

Description

Raises the EContainerIsEmpty exception.


RaiseInvalidIndex Method

Applies to

TContainer

Declaration

class procedure RaiseInvalidIndex;

Description

Raises the EInvalidIndex exception.


RaiseMarkerNotSet Method

Applies to

TContainer

Declaration

class procedure RaiseMarkerNotSet;

Description

Raises the EMarkerNotSet exception.


RaiseNewArraySizeTooSmall Method

Applies to

TContainer

Declaration

class procedure RaiseNewArraySizeTooSmall;

Description

Raises the ENewArraySizeTooSmall exception.


RaiseContainerIsFull Method

Applies to

TContainer

Declaration

class procedure RaiseContainerIsFull;

Description

Raises the EContainerIsFull exception.


RaiseArrayNotSorted Method

Applies to

TContainer

Declaration

class procedure RaiseArrayNotSorted;

Description

Raises the EArrayNotSorted exception.


RaiseInvalidOccurrenceSought Method

Applies to

TContainer

Declaration

class procedure RaiseInvalidOccurrenceSought;

Description

Raises the EInvalidOccurrenceSought exception.


RaiseInvalidArrayCapacity Method

Applies to

TContainer

Declaration

class procedure RaiseInvalidArrayCapacity;

Description

Raises the EInvalidArrayCapacity exception.


TContainer Properties
Size

IsEmpty


Size Property

See Also

Applies to

TContainer

Declaration

property Size : LongInt;

Description

Size is a read-only property which indicates the number of objects currently in the container.


Size Property See Also
See Also

IsEmpty property


IsEmpy Property
IsEmpty Property

See Also

Applies to

TContainer

Declaration

property IsEmpty : Boolean;

Description

IsEmpty is a read-only property that indicates if the container is empty.


IsEmpty Property See Also
See Also

Size property


TArray Class

Properties	Methods

Unit

ObjArray

Description

TArray provides an indexed based container.  All objects are added using the Insert method.  Objects are inserted in the next available index of the array.  If the Size of the array has reached the maximum

Capacity that was specified by the Create constructor,  the array will be resized increasing its capacity by Delta.

Objects may be removed from the container using the Delete method which requires the index of the object to remove.

The ObjArray property is used to access the objects inside the array.  The array is 1 based, so the first object in the array may be accessed as ObjArray[1].  Since this is the default property,  it does not have to be explicitly specified when accessing an object.  For example,  Array[1] is equivalent to Array.ObjArray[1].

The objects in the array may be sorted at any time using the ShellSort or QuickSort method.  A quick sort is desirable when the objects are in random order, while a shell sort is more efficient if the objects are nearly sorted.  After sorting the array, the Sorted property will return True.

If the array is sorted,  the BinarySearch method will perform the most efficient search.  If the array is not sorted,  the LinearSearch method must be used to search for an object in the array.


TArray Properties
Size

IsEmpty

ObjArray

Sorted

Capacity

Delta

FreeSpace


ObjArray Property

Applies to

TArray

Declaration

property ObjArray[const Index : TArrayIndex] : TObject; default;

Description

ObjArray is the property from which objects in the array are accessed. Since this property is the default property of the class, the name of the property may be omitted when accessing the array. For instance, Array.ObjArray[1] is equivalent to Array[1].


Sorted Property

Applies to

TArray

Declaration

property Sorted : Boolean;

Description

Read-only property which indicates if array is currently sorted. To sort  the array, use QuickSort or ShellSort.  The sorted status is maintained automatically by the array on operations such as Insert, Delete, Swap, and, when an object is assigned to the ObjArray property.

NOTE that the sorted property may be inaccurate under one condition; when an object of the array is modified after having been read.  Here is the possible scenario:

Array.QuickSort;

MyObject      := Array[3] as TMyObject;

MyObject.Name := 'New Value';

Now if BinarySearch is involved, the EArrayNotSorted exception may be raised.

To avoid this situation, a new object may replace the old object directly:

Array.QuickSort;

MyObject      := TMyObject.Create;

MyObject.Name := 'New Value';

Array[3]      := MyObject;

Using this approach,  the array will be able to maintain the sorted status accurately. Note that the previous object located at index 3 will be destroyed automatically.


Capacity Property

Applies to

TArray

Declaration

property Capacity : TArrayIndex;

Description

Capacity indicates how many objects the array may contain without being resized.  When an attempt to insert an object into an array that has reached its current capacity,  the capacity will be increased by Delta.

If capacity is written to, the array will be resized to the new capacity.  If the new capacity is not valid, the EInvalidArrayCapacity exception will be raised.


Delta Property

Applies to

TArray

Declaration

property Delta : TArrayIndex;

Description

Delta indicates by how much the Capacity of the array will be increased on an  Insert operation when Size has reached Capacity.  If Delta is 0, the container  will not increase its capacity; the EContainerIsFull exception will be raised when Insert is invoked on a full array.

Delta may be read and written to.


FreeSpace Property

Applies to

TArray

Declaration

property FreeSpace : TArrayIndex;

Description

FreeSpace is a read only property which returns the number of free cells currently available in the array. The Capacity property may be used to increase the free space in the array.


TArray Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

Delete

Swap

LinearSearch

BinarySearch

ShellSort

QuickSort


Create Method

Applies to

TArray

Declaration

constructor Create(

const InObjectType	: TClass;

const InCompareFunc : TCompareFunc;

const InCapacity    : TArrayIndex;

const InDelta       : TArrayIndex

);

Description

Creates an array instance having an initial capacity of InCapacity and a delta of InDelta.


Insert Method

Applies to

TArray

Declaration

procedure Insert(const Obj : TObject);

Description

Inserts Obj in the next available index of the array.  If the array has already reached its maximum Capacity,  its capacity will be increased by Delta.  If the capacity has reached CMaxArrayIndex, or if Delta is 0, then the EContainerIsFull exception will be raised.  If the array was previously Sorted,  then the sorted status may change depending on the value of Obj.


Delete Method

Applies to

TArray

Declaration

procedure Delete(const Index : TArrayIndex);

Description

Deletes and Free's the object located at the Index position in the array.  If Index is not valid, the EInvalidIndex exception will be raised.  The last object in the array will be moved to "fill the hole" at the position of the deleted object.  The Sorted status may be set to False if the array is no longer sorted.


Swap Method

Applies to

TArray

Declaration

procedure Swap(const Index1,Index2 : TArrayIndex);

Declaration

Exchanges the objects located at Index1 and Index2.   If Index1 or Index2  is not valid, the EInvalidIndex exception will be raised.  The Sorted status may be set to False if the array is no longer sorted.


LinearSearch Method

Applies to

TArray

Declaration

function LinearSearch(const Obj : TObject) : TArrayIndex;

Description

Performs a linear search for an object that is equal to Obj in the array.  Equality is determined by using the compare function. If a matching object is found, the index corresponding to the matching object is returned.  Otherwise, CInvalidArrayIndex is returned.


BinarySearch Method

Applies to

TArray

Declaration

function BinarySearch(const Obj : TObject) : TArrayIndex;

Description

Performs a binary search for an object that is equal to Obj in the array.  Equality is determined using the compare function. The array must be sorted before invoking this method.  The sorting may be performed by invoking ShellSort or QuickSort.  If the array is not sorted, the EArrayNotSorted exception will be raised.

If a matching object is found, the index corresponding to the matching object is returned.  Otherwise, CInvalidArrayIndex is returned.


ShellSort Method

Applies to

TArray

Declaration

procedure ShellSort;

Description

Sorts the objects in the array using the Shell-Metzner sort algorithm.  This is an effective algorithm if the array is nearly sorted.  If the array is quite random,  the QuickSort will be more efficient.


QuickSort Method

Applies to

TArray

Declaration

procedure QuickSort;

Description

Sorts the objects in the array using a non recursive quick sort algorithm.  This is an effective algorithm if the array is quite random.  If the array is nearly sorted,  the ShellSort will be more efficient.


TNodeContainer Class

Properties	Methods

Unit

ObjBase

Description

TNodeContainer is an abstract class which provides a common interface for node base containers.

Objects are added to the container using the Insert method.  The Delete method is used to remove a specific object.  Objects are accessed using the CurrentObj property.  Indexed access is also available through the At property.  The current object may be deleted or detached using the DeleteCurrent or DetachCurrent methods respectively.  The Search method is used to find a specific object.

Navigation within the container is provided by various methods.  The GotoFirst and GotoLast methods set the CurrentObj property to the first and last object respectively.  The GotoNext and GotoPrev methods set the CurrentObj property to the next and previous object respectively.  The GotoNth method will set the CurrentObj property to the Nth object.  A marker may be set on an object using the SetMarker method,  and the CurrentObj property may then later be restored to that object using the GotoMarker method.


TNodeContainer Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

Delete

DetachCurrent

DeleteCurrent

Search

GotoNth

GotoFirst

GotoLast

GotoNext

GotoPrev

SetMarker

GotoMarker

IsOnMarker


Create Method

Applies to

TNodeContainer

Declaration

constructor Create(

const InObjectType	: TClass;

const InCompareFunc : TCompareFunc;

);

Description

Creates a container to hold objects belonging to the InObjectType.  Objects will be compared with the InCompareFunc.


Insert Method

Applies to

TNodeContainer

Declaration

procedure Insert(const Obj : TObject); virtual; abstract;

Description

Insert Obj into the container.


Delete Method

Applies to

TNodeContainer

Declaration

function Delete(

const Obj   : TObject;

const Occur : LongInt

) : Boolean; virtual; abstract;

Description

Searches for the Nth Occur'ence of an object that is equal to Obj, and if found, the object is deleted and removed from the container.  Returns True if the object is found and deleted.


DetachCurrent Method

Applies to

TNodeContainer

Declaration

function DetachCurrent : TObject; virtual; abstract;

Description

Detaches the object referenced by CurrentObj from the container.  The object detached is returned.  May raise the EContainerIsEmpty exception.


DeleteCurrent Method

Applies to

TNodeContainer

Declaration

procedure DeleteCurrent; virtual;

Description

Deletes the object referenced by CurrentObj from the container.  May raise the EContainerIsEmpty exception.


Search Method

Applies to

TNodeContainer

Declaration

function Search(

const Obj   : TObject;

const Occur : LongInt

) : Boolean; virtual; abstract;

Description

Searches for the Nth Occur'ence of an object that is equal to Obj, and if found, the CurrentObj property is set to it.  Returns True if the object is found.


GotoNth Method

Applies to

TNodeContainer

Declaration

procedure GotoNth(const Index : LongInt);

Description

Sets the CurrentObj to the object located at the Nth Index.  May raise EInvalidIndex.


GotoFirst Method

Applies to

TNodeContainer

Declaration

function GotoFirst : Boolean; virtual; abstract;

Description

Sets the CurrentObj to the first object in the container.  Returns False if the container is empty.


GotoLast Method

Applies to

TNodeContainer

Declaration

function GotoLast : Boolean; virtual; abstract;

Description

Sets the CurrentObj to the last object in the container.  Returns False if the container is empty.


GotoNext Method

Applies to

TNodeContainer

Declaration

function GotoNext : Boolean; virtual; abstract;

Description

Sets the CurrentObj to the next object in the container.  Returns False if the container is empty or CurrentObj is at the last object.


GotoPrev Method

Applies to

TNodeContainer

Declaration

function GotoPrev : Boolean; virtual; abstract;

Description

Sets the CurrentObj to the previous object in the container.  Returns False if the container is empty or CurrentObj is at the first object.


SetMarker Method

Applies to

TNodeContainer

Declaration

procedure SetMarker;

Description

Sets a marker on the CurrentObj.  If a marker is already set,  it will be replaced by the new marker.  Positioning may then be restored by invoking the GotoMarker method.


GotoMarker Method

Applies to

TNodeContainer

Declaration

procedure GotoMarker;

Description

Restores CurrentObj to the marker previously set by SetMarker.  May raise the EMarkerNotSet exception.


IsOnMarker Method

Applies to

TNodeContainer

Declaration

function IsOnMarker : Boolean;

Description

Returns True if CurrentObj is currently positioned on the last marker set by SetMarker.


TNodeContainer Properties
Size

IsEmpty

CurrentObj

At


CurrentObj Property

Applies to

TNodeContainer

Declaration

property CurrentObj : TObject;

Description

CurrentObj accesses the current object positioned in the container.  For example, these lines will access the first object in a TNodeContainer derived class.

if Container.GotoFirst then

    MyObject := Container.CurrentObj as TMyObject;

This is a read-only property by default, so that the order of objects is not affected in sorted containers.  For non-sorted containers the property may be written to, and the previous object is destroyed before performing the assignment.


At Property

Applies to

TNodeContainer

Declaration

property At[const Index : LongInt] : TObject; default;

Description

The At property is a read-only property that allows an indexed access to the container.  If Index is not within the 1..Size range, the EInvalidIndex exception will be raised.  Since this property is the default property of the class, the name of the property may be omitted when accessing it. For instance, Container.At[1] is equivalent to Container[1].


TOrderedList Class

Properties	Methods

Unit

ObjList

Description

TOrderedList is a  node based container which maintains its objects in a sorted order.  The sort order is determined by the comparison function passed as an argument to the Create constructor.


TOrderedList Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

Delete

DetachCurrent

DeleteCurrent

Search

GotoNth

GotoFirst

GotoLast

GotoNext

GotoPrev

SetMarker

GotoMarker

IsOnMarker


TOrderedList Properties
Size

IsEmpty

CurrentObj

At


TUnOrderedList Class

Properties	Methods

Unit

ObjList

Description

TUnOrderedList is a  node based container which does NOT maintain its objects in a sorted order.  A  comparison function passed as an argument to the Create constructor,  to allow searches with the Search method.


TUnOrderedList Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

InsertAtHead

InsertAtTail

Delete

DetachCurrent

DeleteCurrent

Search

GotoNth

GotoFirst

GotoLast

GotoNext

GotoPrev

SetMarker

GotoMarker

IsOnMarker


InsertAtHead Method

Applies to

TUnOrderedList

Declaration

procedure InsertAtHead(const Obj : TObject);

Description

Inserts Obj at the head of the list.  Invoking GotoFirst will position CurrentObj to the object just inserted.


InsertAtTail Method

Applies to

TUnOrderedList

Declaration

procedure InsertAtTail(const Obj : TObject);

Description

Inserts Obj at the tail of the list.  Invoking GotoLast will position CurrentObj to the object just inserted.


TUnOrderedList Properties
Size

IsEmpty

CurrentObj

At


TCircularList Class

Properties	Methods

Unit

ObjList

Description

TCircularList is an unordered container which has the property that a call to the GotoNext method when CurrentObj is positioned at the last object,  will set the current position to the first object. Similarly,  a call to the GotoPrev method when CurrentObj is positioned at the first object,  will set the current position to the last object.


TCircularList Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

Delete

DetachCurrent

DeleteCurrent

Search

GotoNth

GotoFirst

GotoLast

GotoNext

GotoPrev

SetMarker

GotoMarker

IsOnMarker


GotoNext Method

Applies to

TCircularList

Declaration

procedure GotoNext; override;

Description

Sets the CurrentObj to the next object in the container.  If  CurrentObj is positioned at the last object,  the position will be set to the first object.


GotoPrev Method

Applies to

TCircularList

Declaration

procedure GotoPrev; override;

Description

Sets the CurrentObj to the previous object in the container.  If  CurrentObj is positioned at the first object,  the position will be set to the last object.


TCircularList Properties
Size

IsEmpty

CurrentObj

At


TBinaryTree Class

Properties	Methods

Unit

ObjBTree

Description

TBinaryTree is a  node based container implemented as a non-balanced binary search tree.  The container allows duplicate objects.  The duplicate objects are processed in a first come/first serve basis when the GotoNext and GotoPrev methods are invoked.


TBinaryTree Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

Delete

DetachCurrent

DeleteCurrent

Search

GotoNth

GotoFirst

GotoLast

GotoNext

GotoPrev

SetMarker

GotoMarker

IsOnMarker


TBinaryTree Properties
Size

IsEmpty

CurrentObj

At


THashTable Class

Properties	Methods

Unit

ObjHash

Description

A hash table is a container which provides verify fast insertion and search times, without maintain the held objects in any particular order.  To achieve this result,  a good hash function is required, and the hash table size must be of an appropriate size with respect to the number of objects inserted into the container.  Hashing is the process of generating an index into a table from an object to be stored in the hash table.  When two objects hash to the same index,  a collision is said occur.

THashTable implements a hash table which resolves collisions by chaining the colliding objects into a link list.  The Create method of THashTable requires a hash function and the size of the table.  The StringHash and IntegerHash functions may be used to create hash functions which operate on string and integer keys respectively.  The THashFunc type defines the form of the hash function.

The table size should be determined from the expected number of objects that will be inserted into the hash table.  For example,  if a  table is expected to hold 1000-5000 objects,  a table size of 100 would generate many collisions.  The maximum number of objects that may be inserted into a hash table is only limited by available memory,  but search times will be longer if the table size is too small, or if the hash function generates many collisions.


THashTable Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

Delete

Search


Create Method

Applies to

THashTable

Declaration

constructor Create(

const InObjectType  : TClass;

const InCompareFunc : TCompareFunc;

const InHashFunc    : THashFunc;

const InTableSize   : TArrayIndex

);

Description

Creates a hash table of size InTableSize, to hold objects of type InObjectType.  The objects will be compared with InCompareFunc, and hashed with InHashFunc.


Insert Method

Applies to

THashTable

Declaration

procedure Insert(const Obj : TObject); virtual;

Description

Inserts Obj into the hash table.


Delete Method

Applies to

THashTable

Declaration

function Delete(

const Obj   : TObject;

const Occur : LongInt

) : Boolean; virtual;

Description

Searches for the Nth Occur'ence of an object that is equal to Obj, and if found, the object is deleted and removed from the container.  Returns True if the object is found and deleted.


Search Method

Applies to

THashTable

Declaration

function Search(

const Obj   : TObject;

const Occur : LongInt

) : TObject;

Description

Searches for the Nth Occur'ence of an object that is equal to Obj.  If an object is found, it is returned; if not, nil is returned.


THashTable Properties
Size

IsEmpty


TStringTable Class

Properties	Methods

Unit

StrTable

Description

TStringTable is a hash table which holds strings.  A hash function is provided by the class itself, so the Create method only requires the table size.


TStringTable Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Insert

Delete

Search


Create Method

Applies to

TStringTable

Declaration

constructor Create(const InTableSize : TArrayIndex);

Description

Creates a string table with the size InTableSize.  The maximum number of strings that may be inserted is only limited by available memory,  but if the table size is too small, an excessive number of collisions may occur.


Insert Method

Applies to

TStringTable

Declaration

procedure Insert(

const Str : String;

const Obj : TObject

);

Description

Inserts Str in the string table.  Each string in the table may have an associated object.  If it is not required to associate an object with the string,  nil should be passed for Obj.


Delete Method

Applies to

TStringTable

Declaration

function Delete(

const Str   : String;

const Occur : LongInt

) : Boolean;

Description

Searches for the Nth Occur'ence of Str, and if found, the string is removed from the container.  If Str has an associated object, the object is destroyed.  Returns True if the string is found and deleted.


Search Method

Applies to

TStringTable

Declaration

function Search(

const Str   : String;                        const Occur : LongInt

) : TStringCombo;

Description

Searches for the Nth Occur'ence of Str.  If a string is found, the string and its associated object it is returned as a TStringCombo; if not, nil is returned.


TStringTable Properties
Size

IsEmpty


TQueue Class

Properties	Methods

Unit

ObjQueue

Description

TQueue implements a first in/first out (FIFO) data structure.  Objects are added to the queue with the EnQueue method, and removed from the queue with the DeQueue method.


TQueue Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

EnQueue

DeQueue


Create Method

Applies to

TQueue

Declaration

constructor Create(const InObjectType : TClass);

Description

Creates a queue to hold objects belonging to the InObjectType type.


EnQueue Method

Applies to

TQueue, TPriorityQueue

Declaration

procedure EnQueue(const Obj : TObject); virtual;

Description

Add Obj to the queue.


DeQueue Method

Applies to

TQueue, TPriorityQueue

Declaration

function DeQueue : TObject; virtual;

Description

Removes and returns the object that has been waiting in the queue for the longest time.  If the queue is empty, the EContainerIsEmpty exception is raised.


TQueue Properties
Size

IsEmpty


TPriorityQueue Class

Properties	Methods

Unit

ObjQueue

Description

TPriorityQueue is a queue in which objects are removed in an order based on a priority determined by the comparison function passed as an argument to the Create constructor.  The smallest objects (as determined by the comparison function) are removed first.  Objects of the same priority are treated in a first in/first out manner.

Objects are added to the queue with the EnQueue method, and removed from the queue with the DeQueue method.


TPriorityQueue Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

EnQueue

DeQueue


Create Method

Applies to

TPriorityQueue

Declaration

constructor Create(

const InObjectType  : TClass;

const InCompareFunc : TCompareFunc

);

Description

Creates a queue to hold objects belonging to the InObjectType type.  The priorities are weighted by the InCompareFunc function.


TPriorityQueue Properties
Size

IsEmpty


TStack Class

Properties	Methods

Unit

ObjStack

Description

TStack implements a last in/first out (LIFO) data structure.  Objects are added to the stack with the Push method, and removed from the stack with the Pop method.


TStack Methods
Create

Destroy

Clear

ForEachCallProc

ForEachCallMethod

Push

Pop

PeekTop


Create Method

Applies to

TStack

Declaration

constructor Create(const InObjectType : TClass);

Description

Creates a stack to hold objects belonging to the InObjectType type.


Push Method

Applies to

TStack

Declaration

procedure Push(const Obj : TObject);

Description

Add Obj to the stack.


Pop Method

Applies to

TStack

Declaration

function Pop : TObject;

Description

Removes and returns the must recent object pushed into the stack.  If the stack is empty, the EContainerIsEmpty exception is raised.


PeekTop Method

Applies to

TStack

Declaration

function PeekTop : TObject;

Description

Returns the object that would be removed if Pop was invoked,  but does not remove the object.  If the stack is empty, the EContainerIsEmpty exception is raised.


TStack Properties
Size

IsEmpty


Create Method

Applies to

All TStringCombo and TBucket derived classes

Create method for TStringCombo

Create method for TBucket

Create method for TBooleanBucket

Create method for TByteBucket

Create method for TCharBucket

Create method for TCompBucket

Create method for TDateTimeBucket

Create method for TDoubleBucket

Create method for TExtendedBucket

Create method for TIntegerBucket

Create method for TLongBoolBucket

Create method for TLongIntBucket

Create method for TRealBucket

Create method for TShortIntBucket

Create method for TSingleBucket

Create method for TWordBoolBucket

Create method for TWordBucket


TStringCombo Class

Properties	Methods

Unit

ObjBuckt

Description

TStringCombo is a class that provides the ability to store pascal length byte strings inside containers.   An object may be associated with a TStringCombo. The function, CompareStringCombo should be used with containers that require a compare function.


TStringCombo Methods
Create

Destroy


Create Method

Applies to

TStringCombo

Declaration

constructor Create(

const Str : String;

const Obj : TObject);

Description

Creates a TStringCombo with the string, Str, and the associated object, Obj.  If an associated object is not required, simply pass nil for Obj in the Create constructor.


Destroy Method

Applies to

TStringCombo

Declaration

destructor Destroy; override;

Description

Destroys the object instance, and if an associated object was specified in the Create constructor, this object is also destroyed.


TStringCombo Properties
Str

Obj


Str Property

Applies to

TStringCombo

Declaration

property Str : String;

Description

Str is a read-only property which returns the string that was inserted in the TStringCombo by the Create constructor.


Obj Property

Applies to

TStringCombo

Declaration

property Obj : TObject;

Description

Obj is a read-only property which returns the associated object that was inserted in the TStringCombo by the Create constructor.


TBucket Class

Properties	Methods

Unit

ObjBuckt

Description

TBucket is a class used to store non-object data into containers.  The CreateSetData constructor may be used to create a bucket and set the data at the same time. Or the Create constructor may be used, followed by invoking SetData.  The data in the bucket is retrieved using the GetData method or the DataPtr property.

Click here for more information on how to use the TBucket class to store non-object data into containers.


TBucket Methods
Create

CreateSetData

Destroy

SetData

GetData


Create Method

Applies to

TBucket

Declaration

constructor Create(const InDataSize : Word);

Description

Creates the bucket by allocating the memory to store types which require InDataSize bytes of space.


CreateSetData Method

Applies to

TBucket

Declaration

constructor CreateSetData(

const InDataSize : Word;

const Data);

Description

Creates the bucket by allocating the memory to store types which require InDataSize bytes of space.  InDataSize bytes are copied from Data to the bucket.


Destroy Method

Applies to

TBucket

Declaration

destructor Destroy; override;

Description

Destroys the bucket, and disposes the memory that was allocated to hold the bucket data.


SetData Method

Applies to

TBucket

Declaration

constructor SetData(const Data);

Description

Sets the value of the bucket from Data.  The number of bytes copied from Data is determined by the size of the data that was specified in the Create or CreateSetData constructor.


GetData Method

Applies to

TBucket

Declaration

constructor GetData(var Data);

Description

Retrieves the contents of the bucket into Data.  The number of bytes copied to Data is determined by the size of the data that was specified in the Create or CreateSetData constructor.


TBucket Properties
DataPtr


DataPtr Property

Applies to

TBucket

Declaration

property DataPtr : Pointer;

Description

DataPtr is a read-only property that returns a generic pointer to the data stored in the bucket.


TBooleanBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Boolean data inside containers. The CompareBooleanBucket function should be used with containers holding TBooleanBucket's.


TBooleanBucket Methods
Create


Create Method

Applies to

TBooleanBucket

Declaration

constructor Create(const Data : Boolean);

Description

Creates the bucket and sets the value of the bucket to Data.


TBooleanBucket Properties
Value


Value Property

Applies to

TBooleanBucket

Declaration

property Value : Boolean;

Description

This is a read-only property that returns the value held inside the bucket.


TByteBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Byte data inside containers. The CompareByteBucket function should be used with containers holding TByteBucket's.


TByteBucket Methods
Create


Create Method

Applies to

TByteBucket

Declaration

constructor Create(const Data : Byte);

Description

Creates the bucket and sets the value of the bucket to Data.


TByteBucket Properties
Value


Value Property

Applies to

TByteBucket

Declaration

property Value : Byte;

Description

This is a read-only property that returns the value held inside the bucket.


TCharBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Char data inside containers. The CompareCharBucket function should be used with containers holding TCharBucket's.


TCharBucket Methods
Create


Create Method

Applies to

TCharBucket

Declaration

constructor Create(const Data : Char);

Description

Creates the bucket and sets the value of the bucket to Data.


TCharBucket Properties
Value


Value Property

Applies to

TCharBucket

Declaration

property Value : Char;

Description

This is a read-only property that returns the value held inside the bucket.


TCompBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Comp data inside containers. The CompareCompBucket function should be used with containers holding TCompBucket's.


TCompBucket Methods
Create


Create Method

Applies to

TCompBucket

Declaration

constructor Create(const Data : Comp);

Description

Creates the bucket and sets the value of the bucket to Data.


TCompBucket Properties
Value


Value Property

Applies to

TCompBucket

Declaration

property Value : Comp;

Description

This is a read-only property that returns the value held inside the bucket.


TDateTimeBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store TDateTime data inside containers. The CompareDateTimeBucket function should be used with containers holding TDateTimeBucket's.


TDateTimeBucket Methods
Create


Create Method

Applies to

TDateTimeBucket

Declaration

constructor Create(const Data : TDateTime);

Description

Creates the bucket and sets the value of the bucket to Data.


TDateTimeBucket Properties
Value


Value Property

Applies to

TDateTimeBucket

Declaration

property Value : TDateTime;

Description

This is a read-only property that returns the value held inside the bucket.


TDoubleBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Double data inside containers. The CompareDoubleBucket function should be used with containers holding TDoubleBucket's.


TDoubleBucket Methods
Create


Create Method

Applies to

TDoubleBucket

Declaration

constructor Create(const Data : Double);

Description

Creates the bucket and sets the value of the bucket to Data.


TDoubleBucket Properties
Value


Value Property

Applies to

TDoubleBucket

Declaration

property Value : Double;

Description

This is a read-only property that returns the value held inside the bucket.


TExtendedBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Extended data inside containers. The CompareExtendedBucket function should be used with containers holding TExtendedBucket's.


TExtendedBucket Methods
Create


Create Method

Applies to

TExtendedBucket

Declaration

constructor Create(const Data : Extended);

Description

Creates the bucket and sets the value of the bucket to Data.


TExtendedBucket Properties
Value


Value Property

Applies to

TExtendedBucket

Declaration

property Value : Extended;

Description

This is a read-only property that returns the value held inside the bucket.


TIntegerBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Integer data inside containers. The CompareIntegerBucket function should be used with containers holding TIntegerBucket's.


TIntegerBucket Methods
Create


Create Method

Applies to

TIntegerBucket

Declaration

constructor Create(const Data : Integer);

Description

Creates the bucket and sets the value of the bucket to Data.


TIntegerBucket Properties
Value


Value Property

Applies to

TIntegerBucket

Declaration

property Value : Integer;

Description

This is a read-only property that returns the value held inside the bucket.


TLongBoolBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store LongBool data inside containers. The CompareLongBoolBucket function should be used with containers holding TLongBoolBucket's.


TLongBoolBucket Methods
Create


Create Method

Applies to

TLongBoolBucket

Declaration

constructor Create(const Data : LongBool);

Description

Creates the bucket and sets the value of the bucket to Data.


TLongBoolBucket Properties
Value


Value Property

Applies to

TLongBoolBucket

Declaration

property Value : LongBool;

Description

This is a read-only property that returns the value held inside the bucket.


TLongIntBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store LongInt data inside containers. The CompareLongIntBucket function should be used with containers holding TLongIntBucket's.


TLongIntBucket Methods
Create


Create Method

Applies to

TLongIntBucket

Declaration

constructor Create(const Data : LongInt);

Description

Creates the bucket and sets the value of the bucket to Data.


TLongIntBucket Properties
Value


Value Property

Applies to

TLongIntBucket

Declaration

property Value : LongInt;

Description

This is a read-only property that returns the value held inside the bucket.


TRealBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Real data inside containers. The CompareRealBucket function should be used with containers holding TRealBucket's.


TRealBucket Methods
Create


Create Method

Applies to

TRealBucket

Declaration

constructor Create(const Data : Real);

Description

Creates the bucket and sets the value of the bucket to Data.


TRealBucket Properties
Value


Value Property

Applies to

TRealBucket

Declaration

property Value : Real;

Description

This is a read-only property that returns the value held inside the bucket.


TShortIntBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store ShortInt data inside containers. The CompareShortIntBucket function should be used with containers holding TShortIntBucket's.


TShortIntBucket Methods
Create


Create Method

Applies to

TShortIntBucket

Declaration

constructor Create(const Data : ShortInt);

Description

Creates the bucket and sets the value of the bucket to Data.


TShortIntBucket Properties
Value


Value Property

Applies to

TShortIntBucket

Declaration

property Value : ShortInt;

Description

This is a read-only property that returns the value held inside the bucket.


TSingleBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Single data inside containers. The CompareSingleBucket function should be used with containers holding TSingleBucket's.


TSingleBucket Methods
Create


Create Method

Applies to

TSingleBucket

Declaration

constructor Create(const Data : Single);

Description

Creates the bucket and sets the value of the bucket to Data.


TSingleBucket Properties
Value


Value Property

Applies to

TSingleBucket

Declaration

property Value : Single;

Description

This is a read-only property that returns the value held inside the bucket.


TWordBoolBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store WordBool data inside containers. The CompareWordBoolBucket function should be used with containers holding TWordBoolBucket's.


TWordBoolBucket Methods
Create


Create Method

Applies to

TWordBoolBucket

Declaration

constructor Create(const Data : WordBool);

Description

Creates the bucket and sets the value of the bucket to Data.


TWordBoolBucket Properties
Value


Value Property

Applies to

TWordBoolBucket

Declaration

property Value : WordBool);

Description

This is a read-only property that returns the value held inside the bucket.


TWordBucket Class

Properties	Methods

Unit

ObjBuckt

Description

This is a specialized bucket class to store Word data inside containers.  The CompareWordBucket function should be used with containers holding TWordBucket's.


TWordBucket Methods
Create


Create Method

Applies to

TWordBucket

Declaration

constructor Create(const Data : Word);

Description

Creates the bucket and sets the value of the bucket to Data.


TWordBucket Properties
Value


Value Property

Applies to

TWordBucket

Declaration

property Value : Word;

Description

This is a read-only property that returns the value held inside the bucket.


Spider Library Units

ObjArray

Array class and related types

ObjBase

Abstract container classes

ObjBTree

Binary Tree class and related types

ObjBuckt

Buckets to store non-object data in containers

ObjCmp

Comparison function and types

ObjHash

THashTable class and related types

ObjList

List classes and related types

ObjQueue

Queue, Priority Queue classes and related types

ObjStack

Stack class and related types

StrTable

TStringTable class and related types


ObjBase Unit

The ObjBase unit contains the declarations for abstract container classes, from which all other containers derive from.

Classes

TContainer

TNodeContainer

Types

TProcIterator

TMethodIterator

Exceptions


TProcIterator Type

Unit

ObjBase

Declaration

TProcIterator = procedure(const Obj : TObject);

Description

This is the procedure type used with the ForEachCallProc iterator method of TContainer.


TMethodIterator Type

Unit

ObjBase

Declaration

TMethodIterator = procedure(const Obj : TObject) of object;

Description

This is the method type used with the ForEachCallMethod iterator method of TContainer.


ObjQueue Unit

The ObjQueue unit contains the declarations for the queue and priority queue classes.

Classes

TQueue

TPriorityQueue


ObjBTree Unit

The ObjBTree unit contains the declaration for the binary tree class.

Classes

TBinaryTree


ObjList Unit

The ObjList unit contains the declarations for the ordered list, unordered list, and circular list classes.

Classes

TOrderedList

TUnOrderedList

TCircularList


ObjArray Unit

The ObjArray unit contains the declaration for the array class.

Classes

TArray

Constants

CMaxArrayIndex

CInvalidArrayIndex

Types

TArrayIndex


CMaxArrayIndex Constant

Unit

ObjArray

Declaration

{$ifdef Win32}

MaxLongInt div 4;

{$else}

($FFFF - 16) div 4;

{$endif}

Thus giving a theoretical limit maximum of 536870911 objects in 32-bits, and 16379 objects in 16-bits.

Description

CMaxArrayIndex is the maximum array index that may be used with a TArray instance. Under the 16-bit version of Delphi, this index is limited by the size of a segment.


CInvalidArrayIndex Constant

Unit

ObjArray

Declaration

CInvalidArrayIndex = 0;

Description

CInvalidArrayIndex is a constant which defines an invalid array index used with a TArray instance. It may be used in certain occasions, for example, to indicate an unsuccessful search on an array.


TArrayIndex Type

Unit

ObjArray

Declaration

TArrayIndex = CInvalidArrayIndex ..CMaxArrayIndex;

Description

TArrayIndex is the type used to define the index range used with a TArray instance.


ObjStack Unit

The ObjStack unit contains the declaration for the stack class.

Classes

TStack


ObjBuckt Unit

The ObjBuckt unit contains the declaration for bucket classes that are used to store non-object data in containers.

Classes

TBooleanBucket

TBucket

TByteBucket

TCharBucket

TCompBucket

TDateTimeBucket

TDoubleBucket

TExtendedBucket

TIntegerBucket

TLongBoolBucket

TLongIntBucket

TRealBucket

TShortIntBucket

TSingleBucket

TStringCombo

TWordBoolBucket

TWordBucket

Procedures And Functions

CompareBooleanBucket

CompareByteBucket

CompareCharBucket

CompareCompBucket

CompareDateTimeBucket

CompareDoubleBucket

CompareExtendedBucket

CompareIntegerBucket

CompareLongBoolBucket

CompareLongIntBucket

CompareRealBucket

CompareShortIntBucket

CompareSingleBucket

CompareStringCombo

CompareWordBoolBucket

CompareWordBucket


CompareBooleanBucket Function

Unit

ObjBuckt

Declaration

function CompareBooleanBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TBooleanBucket's.


CompareByteBucket Function

Unit

ObjBuckt

Declaration

function CompareByteBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TByteBucket's.


CompareCharBucket Function

Unit

ObjBuckt

Declaration

function CompareCharBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TCharBucket's.


CompareCompBucket Function

Unit

ObjBuckt

Declaration

function CompareCompBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TCompBucket's.


CompareDateTimeBucket Function

Unit

ObjBuckt

Declaration

function CompareDateTimeBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TDateTimeBucket's.


CompareDoubleBucket Function

Unit

ObjBuckt

Declaration

function CompareDoubleBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TDoubleBucket's.


CompareExtendedBucket Function

Unit

ObjBuckt

Declaration

function CompareExtendedBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TExtendedBucket's.


CompareIntegerBucket Function

Unit

ObjBuckt

Declaration

function CompareIntegerBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TIntegerBucket's.


CompareLongBoolBucket Function

Unit

ObjBuckt

Declaration

function CompareLongBoolBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TLongBoolBucket's.


CompareLongIntBucket Function

Unit

ObjBuckt

Declaration

function CompareLongIntBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TLongIntBucket's.


CompareRealBucket Function

Unit

ObjBuckt

Declaration

function CompareRealBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TRealBucket's.


CompareShortIntBucket Function

Unit

ObjBuckt

Declaration

function CompareShortInt(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TShortIntBucket's.


CompareSingleBucket Function

Unit

ObjBuckt

Declaration

function CompareSingle(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TSingleBucket's.


CompareStringCombo Function

Unit

ObjBuckt

Declaration

function CompareStringCombo(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TStringCombo's.


CompareWordBoolBucket Function

Unit

ObjBuckt

Declaration

function CompareWordBoolBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TWordBoolBucket's.


CompareWordBucket Function

Unit

ObjBuckt

Declaration

function CompareWordBucket(const Lhs, Rhs : TObject) : TComparison; far;

Description

This is the comparison function that should be used with containers holding TWordBucket's.


ObjCmp Unit

The ObjCmp unit contains the declarations used to perform comparison between object instances within containers.

Types

TComparison

TCompareFunc

Procedures and Functions

CompareString

CompareReal

CompareInteger


TComparison Type

Unit

ObjCmp

Declaration

TComparison = (cmpEqual, cmpLess, cmpGreater);

Description

These are the possible return values for functions of the TCompareFunc form.


TCompareFunc Type

Unit

ObjCmp

Declaration

TCompareFunc = function(const Lhs, Rhs : TObject) : TComparison;

Description

This is the function type used when comparing objects.  Lhs and Rhs stand for "left hand side" and "right hand side" respectively.

Functions of this form should return:

cmpEqual, when Lhs = Rhs

cmpGreater, when Lhs > Rhs,

cmpLess, when Lhs < Rhs


CompareString Function

Unit

ObjCmp

Declaration

function CompareString(const Lhs, Rhs : String) : TComparison; far;

Description

This is a function that may be used within a TCompareFunc function when objects are compared with respect to strings.  The comparison is case sensitive.

Here is a typical use:

function CompareMyObject( const Lhs, Rhs : TObject) : TComparison;

begin

    Result := CompareString(

(Lhs as TMyObject).Str,

(Rhs as TMyObject).Str

);

end;

This assumes that the TMyObject has a property called Str.


CompareReal Function

Unit

ObjCmp

Declaration

function CompareReal(const Lhs, Rhs : Extended) : TComparison; far;

Description

This is a function that may be used within a TCompareFunc function when objects are compared with respect to real numbers (Extended, Double, Single, or Real).


CompareInteger Function

Unit

ObjCmp

Declaration

function CompareInteger(const Lhs, Rhs : LongInt) : TComparison; far;

Description

This is a function that may be used within a TCompareFunc function when objects are compared with respect to integer based numbers (LongInt, ShortInt, SmallInt, Word, Byte).


ObjHash Unit

The ObjHash unit contains the declaration for the hash table class.

Classes

THashTable

Types

THashFunc

Procedures and Functions

IntegerHash

StringHash


THashFunc Type

Unit

ObjHash

Declaration

THashFunc = function(

const Obj       : TObject;

const TableSize : TArrayIndex

) : TArrayIndex;

Description

The THashFunc type defines the form of a hash function to be used with a THashTable.

The function must return an index from 1..TableSize as a function

of Obj.  A good hash function should distribute the indexes in a uniform manner for the objects inserted into the hash table.


IntegerHash Function

Unit

ObjHash

Declaration

function IntegerHash(

const Value     : LongInt;

const TableSize : TArrayIndex

) : TArrayIndex; far;

Description

This is a function that may be used within a THashFunc function when hashing is performed on integer types (LongInt, ShortInt, SmallInt, Word, Byte).

Here is a typical use:

function MyObjectHash(

const Obj       : TObject;

const TableSize : TArrayIndex

) : TArrayIndex;

begin

    Result := IntegerHash(

(Lhs as TMyObject).Val,

TableSize

);

end;

This assumes that the TMyObject has a property called Val.


StringHash Function

Unit

ObjHash

Declaration

function StringHash(

const Value     : String;

const TableSize : TArrayIndex

) : TArrayIndex; far;

Description

This is a function that may be used within a THashFunc function when hashing is performed on strings.


StrTable Unit

The StrTable unit contains the declaration for the string table.

Classes

TStringTable


Which container should I use?

Should the container allow the sorting of objects?   Yes   No

Should the objects be retrieved always in the same order?   Yes


Container with items not sorted

Do you require a very fast search?   Yes   No


Non sorted fast search container

A THashTable container delivers very fast search times in a non-sorted container, while maintaining very fast insertion times.

If you require a hash table to hold strings, then you may use a TStringTable. This class implements a hash table for pascal length byte strings, without having to deal with any object instances.


Non sorted regular search times

If you require a fast indexed access then use the TArray container, which has very fast insertion times and a direct indexed access. If you do not sort the array, search times will be proportional to the number of objects in the container using the LinearSearch method. If you sort the array, then you will get fast indexed access, and fast search times using the BinarySearch method.

If you require navigational access (moving to next and previous objects) to be built in the container, then use the TUnOrderedList container, which has fast insertion times, but a search time that is proportional to the number of objects in the container. If you want the navigational access to behave as a "loop" (moving from the last object to the first object on a "next" operation, or from first to last on a "previous" operation) then use the TCircularList container. You may still use an indexed access on unordered and circular lists, but when the container has many objects, it is more efficient to use an array.


Sorted Container Decision

Should the sort order be maintained after every addition?   Yes   No


Sorted container with order maintained

If the number of objects in the container is small (less than about 1000) then the TOrderedList is fine.  A binary tree can also be used, but it requires more memory for each node, so this overhead is not necessary if the list is not very large.

Use the TBinaryTree if there are going to be many objects in the container and fast search times are required.


Sorted container with order not maintained

You may use the TArray container with very fast insertion times to add objects in a non sorted fashion. Then you may sort the array on demand with the array's QuickSort or ShellSort methods.


Specific Retrieval Container

If the items in container are to be retrieved in a Last In / First Out (LIFO) fashion then use a TStack instance.

If the items in container are to be retrieved in a First In / First Out (FIFO) fashion then use a TQueue instance.

If you require a container which operates in a FIFO fashion, with the exception that a priority associated with each object may modify the retrieval order, use a TPriorityQueue. For example, items inserted at a higher priority, will be retrieved before items with a lower priority, even if the lower priority item has been inserted first. Items with the same priority are treated in a FIFO fashion.


Exceptions for Spider Container Classes

All exceptions generated by the container classes are centralized in TContainer class methods, for simpler maintenance.

Here are the exceptions that may be generated by container classes:

EInvalidObjectType

EContainerIsEmpty

EInvalidIndex

EMarkerNotSet

ENewArraySizeTooSmall

EContainerIsFull

EArrayNotSorted


EInvalidObjectType Exception

This exception is raised when an object passed to TContainer (or derived class) method  is not of the proper type defined when the container was constructed.


EContainerIsEmpty Exception

This exception is raised when an operation on an empty container is invalid.

This may occur in any of the following cases:

When a Pop operation is performed on an empty TStack instance.

When a DeQueue operation is performed on an empty TQueue or TPriorityQueue instance.

When a DetachCurrent or DeleteCurrent operation is performed on an empty TNodeContainer (or derived class) instance.

When the CurrentObj property of an empty TNodeContainer (or derived class) instance is accessed.


EInvalidIndex Exception

This exception is raised when the index used on a TArray instance is not within the bounds of the array.

This exception is also raised when the default At property of a TNodeContainer (or derived class) instance is invoked with an invalid index.


EMarkerNotSet Exception

This exception is raised when a GotoMarker operation is invoked on a TNodeContainer (or derived class) instance, without first having performed a SetMarker operation.


ENewArraySizeTooSmall Exception

This exception is raised when the Capacity property of a TArray instance is modified to a new size which is smaller than the current number of objects in the array.


EContainerIsFull Exception

This exception is raised when an insertion cannot be completed on a container which is considered full.

This may occur when inserting in a TArray instance under 2 conditions:

1.  The array has reached a maximum of CMaxArrayIndex objects,

or

2. The array was created with a Delta of 0, indicating that once the array has reached its maximum capacity, it may not be resized.


EArrayNotSorted Exception

This exception is raised when a BinarySearch operation is invoked on a non-sorted TArray instance. The array should have been previously sorted by invoking ShellSort or QuickSort.


EInvalidOccurrenceSought Exception

This exception is raised when a when a negative or zero'th occurrence of an object is searched in any TContainer derived class.


EInvalidArrayCapacity Exception

This exception is raised when a invalid capacity value (less then 1) is used to  create or change the capacity of a TArray instance.


Multi-Language Support

All error messages for the container exceptions are linked in the final executable from a resource file.  If the container classes are used in applications not targeted for an English market,   the resource files, Spider16.Res or Spider32.Res (depending if the target is 16 or 32 bit) should be edited.  The string table should be converted to the proper language using a resource editor, such as Borlands's Resource Workshop. Re-compiling the application will bind the new resource file to the executable.


Evaluation Version

Executables produced by the evaluation version of the Spider Container classes will only function when the Delphi environment is running.  The evaluation version includes source code for the example application, but full source code for all the container classed will be shipped upon purchase of the container classes.


Contact Information

Interval Software

16 Ste-Madeleine

Rigaud, Quebec, Canada

J0P 1P0

The latest information on the Spider Containers for Object Pascal may be found on the internet at:

http://www.cam.org/~mibra/spider

Any questions may be forwarded to by email, to:

mibra@cam.org


How To Purchase

The Spider Containers for Object Pascal may be purchased using various payment methods.  The usage of the library is subject to the licensing terms.

These are the available payment methods:

Via Compuserve

Go to the SWREG forum.  The registration Id is 10935.

By credit card (Visa or MasterCard)

Fill out and send the order form.

By check

Fill out and send the order form.


Order Form
Spider Containers for Object Pascal - ORDER FORM

Mail order form to:

Interval Software

16 Ste-Madeleine

Rigaud, Quebec, Canada

J0P 1P0

Name:	__________________________________

Email:	__________________________________

Street:	__________________________________

City:	__________________________________

State/Prov:	__________________________________

Country:  	__________________________________

Zip/PC:	__________________________________

Pricing

The price is 15$ US or 20$ Canadian, and includes all applicable taxes and shipping.

Quantity: _____	Total: __________

Payment Methods

Checks must be drawn from a Canadian or US bank, payable to Interval Software.

Please note that for credit card payments, your order will be charged in Canadian dollars at the current exchange rate.

Compuserve	[  ] (Go SWREG, ID 10935. Do NOT send the order form)

Check	[  ]

Visa	[  ]

Master Card 	[  ]

Card #:	________________________________________

Expiration Date:	________________________________________

Name on Card:	________________________________________

Signature:	________________________________________


Licensing and Legal Information

The usage of the Spider Containers for Object Pascal software product indicates your understanding and acceptance of the following terms. This license will supercede any statement, verbal or written, to the contrary.  If you do not accept these terms, or your local legal regulations prohibit exclusion of implied warranties or limited disclaimers, you must cease using the product immediately.

This software product is provided as is, without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the use of this product is assumed by the user. Neither Michel Brazeau, nor any distributor assumes any liability for direct or indirect damages including any lost profits, lost savings, or other incidental or consequential damages arising from any defects, or the use or inability to use this product, even if Michel Brazeau has been advised of the possibility of such damages.

Binary files produced by using the Spider Containers for Object Pascal may be distributed royalty free. The source code of the library may not be distributed by any means, without prior consent in writing, from Michel Brazeau.

This software product may be used only by a single person, on a single computer at a time. The software may be copied from one computer to another, provided that it is used only by a single person, on a single computer at a time. If this product is used in a development team, all members of the team using the product must purchase an individual license.

The Spider Containers for Object Pascal product is Copyrighted © 1996, Michel Brazeau, all rights reserved. This product is protected by Canadian and United States copyright laws, international treaties and all other applicable national or international laws. This software product and documentation may not be reproduced or translated, in part, or in whole, to any electronic medium or machine readable form, without prior consent in writing, from Michel Brazeau and according to all applicable laws. The sole owner of this product is Michel Brazeau.